# Use CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) allows us to write CSS code in a modular way, and these styles can be imported and used in JavaScript files. Using CSS Modules can automatically generate unique class names, isolate styles between different modules, and avoid class name conflicts.

Rsbuild supports CSS Modules by default, you don't need to add additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.

The following style files are considered CSS Modules:

- `*.module.css`
- `*.module.less`
- `*.module.sass`
- `*.module.scss`
- `*.module.styl`
- `*.module.stylus`

## Usage Example

- Write style:

```css title="button.module.css"
.red {
  background: red;
}
```

- Using styles:

```tsx title="Button.tsx"
import styles from './button.module.css';

export default () => {
  return <button className={styles.red}>Button</button>;
};
```

## Named Import

If you prefer to use named imports in CSS Modules, you can enable it through the [output.cssModules.namedExport](/config/output/css-modules#cssmodulesnamedexport) config.

```ts title="rsbuild.config.ts"
export default {
  output: {
    cssModules: {
      namedExport: true,
    },
  },
};
```

If enabled, you can reference class names using named imports:

```tsx title="Button.tsx"
import { red } from './button.module.css';

export default () => {
  return <button className={red}>Button</button>;
};
```

## CSS Modules Recognition Rules

By default, only files ending with `*.module.css` are recognized as CSS Modules.

If you want to treat other CSS files as CSS Modules as well, you can achieve this by configuring [output.cssModules.auto](/config/output/css-modules#cssmodulesauto).

For example:

```ts
export default {
  output: {
    cssModules: {
      auto: (resource) => {
        return resource.includes('.module.') || resource.includes('shared/');
      },
    },
  },
};
```

After this configuration, the following two files will be recognized as CSS Modules:

```ts
import styles1 from './foo.module.css';
import styles2 from './shared/bar.css';
```

## Custom Class Names

Customizing the class names generated by CSS Modules is also a commonly used function, you can use [output.cssModules.localIdentName](/config/output/css-modules#cssmoduleslocalidentname) to configure it.

```ts
export default {
  output: {
    cssModules: {
      localIdentName: '[hash:base64:4]',
    },
  },
};
```

If you need to customize other configs of CSS Modules, you can set them via [output.cssModules](/config/output/css-modules).

## Type Declaration

When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the CSS Modules, please create a `src/env.d.ts` file, and add the corresponding type declaration.

- Method 1: If the `@rsbuild/core` package is installed, you can reference the [preset types](/guide/basic/typescript#preset-types) provided by `@rsbuild/core`:

```ts
/// <reference types="@rsbuild/core/types" />
```

- Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.sass' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.less' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.styl' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.stylus' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
```

- Method 3: If you need to use **named imports** to reference class names, you can use a looser type declaration:

```ts title="src/env.d.ts"
declare module '*.module.css';
declare module '*.module.scss';
declare module '*.module.sass';
declare module '*.module.less';
declare module '*.module.styl';
declare module '*.module.stylus';
```

After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `env.d.ts` is located, making sure the TypeScript can correctly identify the type definition.

## Type Generation

Although the above method can provide the type of CSS Modules, it cannot accurately prompt which classNames are exported by a certain CSS file.

Rsbuild supports generating accurate type declarations for CSS Modules, you only need to register the [@rsbuild/plugin-typed-css-modules](https://github.com/rspack-contrib/rsbuild-plugin-typed-css-modules), and then execute the build, Rsbuild will generate type declaration files for all CSS Modules.

```ts file=rsbuild.config.ts
import { pluginTypedCSSModules } from '@rsbuild/plugin-typed-css-modules';

export default {
  plugins: [pluginTypedCSSModules()],
};
```

### Example

For example, create two files named `src/index.ts` and `src/index.module.css`:

```tsx title="src/index.ts"
import styles from './index.module.css';

console.log(styles.pageHeader);
```

```css title="src/index.module.css"
.page-header {
  color: black;
}
```

After building, Rsbuild will generate a `src/index.module.css.d.ts` type declaration file:

```ts title="src/index.module.css.d.ts"
interface CssExports {
  'page-header': string;
  pageHeader: string;
}
declare const cssExports: CssExports;
export default cssExports;
```

Now when you open the `src/index.ts` file, you can see that the `styles` object already has an accurate type.
